# Quick Start

## Как работает KubeLatte?  

KubeLatte работает как динамический контроллер приема входящих соединений ([dynamic admission controller](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/)) в кластере Kubernetes. Сервер Kubelatte позволяет гибко контролировать работу с ресурсами в кластре Kubernetes.

Kubelatte предполагает несколько режимов работы: валидатор, мутатор и креатор.

- Валидатор обеспечивает корректность написания конфигураций ресурсов кластера
- Мутатор  позволяет модифицировать любые ресурсы кластера при их публикаци или изменении.
- Креатор - это процесс автоматической публикации объектов системы Kubernetes

Политики KubeLatte соответствуют схеме ресурсов, используя структуру конкретного ресурса.
Важным преимуеством является возможность настраивать сценарии мутации и валидации по множеству полей ресусов Kubernetes, политики, конфигурирующие условия начала мутации или валидации, можно гибко и точно настраивать при помощи специального поля match.
Также состав API CRD Kubelatte включает в себя служебный ресурс, запускающий создание ресурсов, при наличии в нем лейбла/аннотации, удовлетворяющими соответствующую политику. 

Политики валидации позволяют разграничить ресурсы на группы, к которым применяются правила валидации при помощи секции match.
Правила позволяют нативно проверить значение любой секции.
Также базовый функционал валидации поддерживает язык rego.
Валидирующие правила используют особый синтаксис: сперва выполняется поиск по мутируемой/создаваемой конфигурации, после регулярное выражение конкретного правила маскирует результат поиска, в зависимости от результата поиска публикация ресурса может быть одобрена или отклонена.

На рисунке ниже показана высокоуровневая логическая архитектура KubeLatte.

![image arch](arch.png)

**Webhook** - это сервер, который обрабатывает входящие запросы AdmissionReview от сервера API Kubernetes и отправляет их на обработку в Mutation или Validation manager. Для обеспечения запросов на данный сервер необходимо настроить MutatingWebhookConfiguration/ValidatingWebhookConfiguration в рамках вашего кластера. После принятия запроса на мутацию/валидацию сервер может динамически настраиваться для более точной детерминации возможности мутации/валидации по вашим политикам Kubelatte (секция match в рамках Trigger/Scope). Далее webhook server направляет запрос на мутацию или валидацию в соответвующий manager.

**Mutation Manager** обрабатывает пришедший ресурс, по надобности мутирует его, использую политики template и trigger. В политике типа Trigger указываются условия для начала мутации (секция match) и ссылки на соответвующие шаблоны для выполнения мутации. В самом шаблоне (тип Template) описываются мутируемые поля по схеме мутируемого ресурса.

**Validation Manager** проводит процесс валидации ресурсов из admission review по правилам, описанным в политике типа Scope, в случае нарушений, может отклонить создание ресурса.

Процесс создания ресурсов выделяется, так как **Creation Manager** следит за появлением ресурса типа TriggerInstance, и в случае, если в нем указан правильный лейбл или аннотация, описанные по аналогии с мутацией в ресурсе типа Trigger, то Creation Manager инициализирует запрос к API сервер Kubernetes по созданию подов описанных в шаблонах (тип Template), перечисленных в секции Trigger со ссылкой на реализуемую лейбл/аннотацию.

Настройка MutatingWebhookConfiguration/ValidatingWebhookConfiguration и конфигураций Kubelatte позволяет использование как одного режима работы, так и всех трех последовательно.

## Quick Start Guide

Этот раздел предназначен для предоставления вам кратких руководств по запуску и демонстрации нескольких ключевых функций KubeLatte.

Данные быстрые руководства, которые фокусируются на мутации, валидации и креации, позволяют познакомиться с основными функциями Kubelatte. Эти руководства предназначены только для демонстраций в лабораторных условиях или для демострации концепции.

1. Установите KubeLatte согласно краткому [руководству](install.md).

   Перед началом реализации необходимо ознакомиться с ограничениями по мутации, которые описываются в рамках конфигурации «kind: Scope». 
   
   ```shell
   ns=<KUBELATTE NAMESPACE>
   ```
 
   #### kind: Scope
   
   Эта конфигурация позволяет понять: «Можно ли проводить мутацию?», «Для каких ресурсов мы проводим мутацию или валидацию?»  
   
   Пример конфигурации:
   ```yaml
   apiVersion: kubelatte.io/v1alpha1
   kind: Scope
   metadata:
     name: busybox-injection-validation
   spec:
     items:
       - name: allowed-containers
         path: spec.containers[*]
         value: .*
         kind: Pod
         apiVersion: v1
       - name: allowed-mutation
         path: keys(metadata.labels)
         value: 'kblt\.mutation\.resource'
         kind: Pod
         apiVersion: v1
   ```

2. Выберите быстрое руководство, которое вас интересует:

- [Мутация](#мутация)
- [Креация](#креация)
- [Валидация](#валидация)

(Альтернативно двигайтесь по инструкции сверху вниз)


### Мутация

Мутация - это возможность изменить, то есть "мутировать" любой ресурс каким-либо образом в момент его раскатки в кластере.  
Мутацию можно легко конфигурировать. Для описания конкретной мутации необходимо реализовать два ресурса API группы Kubelatte - **Template** и **Trigger**.

(Поля конфигураций аналогичны полям для .yaml-файлов Kubernetes)

#### kind: Template

Конфигурация «kind: Template» предназначена для реализации «шаблона» с описанием изменяемой части для любого ресурса системы. К описанным полям в секции «data» данной конфигурации фактически будут применены изменения (эти изменения описаны в аннотации или метке label в конфигурации «kind: Trigger», описано ниже). Обращаем ваше внимание, что структура шаблона пода в секции «data» совпадает с фактической реализацией sidecar.

Добавьте данный шаблон мутации в свой кластер.

```shell
kubectl create -n $ns -f - << EOF
apiVersion: kubelatte.io/v1alpha1
kind: Template
metadata:
  name: busybox-template
spec:
  apiVersion: v1
  kind: Pod
  data: |-
    spec:
      containers:
        - image: busybox
          command: ["/bin/sh"]
          args: ["-c", "while true; do echo 'Hi I am busybox sidecar. I was started at' $(date -u); sleep 5;done"]
          name: busybox
          resources: {}
EOF
```

Подробнее о «kind: Template» можно найти [здесь](../Reference/Configuration/Mutation/template.md).

#### kind: Trigger

Конфигурация предназначена для фильтра входящих запросов на мутацию, необходимой для инициализации мутации. Также в данной конфигурации описывается список контейнеров/аннотаций/томов (для их мутации в пользовательском ресурсе).

Теперь следует реализовать правила, по которым будет вызываться инжектирование описанного ранее sidecar.

```shell
kubectl create -n $ns -f - << EOF
apiVersion: kubelatte.io/v1alpha1
kind: Trigger
metadata:
  name: busybox-injection-trigger
spec:
  mutationConfigs:
    - name: busybox-injection
      match:
        kinds:
          - apiGroups:
              - ''
            kinds:
              - Pod
        name:
          value: nginx
        annotationSelector:
          matchExpressions:
            - key: busybox-injection
              operator: In
              values:
                - enabled
        operations:
          - CREATE
      updateStrategy: merge
      templateRefs:
        - $ns/busybox-template
EOF
```

В данном примере мы видим, что собираемся мутировать Pod с именем nginx, на котором реализована аннотация, описанная в селекторе в рамках секции match. Также указывается ссылка на опубликованный ранее template (ссылка реализована в виде <NAMESPACE>/<NAME OF TEMPALTE>).

Подробнее о «kind: Trigger» можно найти [здесь](../Reference/Configuration/Mutation/trigger.md).

#### Теперь все готово для мутации!

Реализуем под nginx с данной аннотацией:

```shell
kubectl run nginx --image nginx --annotations kblt.synapse/busybox-injection=enabled -n $ns
```

Запросив логи, убеждаемся что нужный нам сайдкар опубликован в рамках пода.

```shell
kubectl logs nginx -c busybox --tail=5 -n $ns
```

Сравним два пода: опубликованный с аннотацией для мутации

Под без мутации:

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    run: nginx
spec:
  containers:
    - name: nginx
      image: nginx
      resources: {}
      imagePullPolicy: Always
  restartPolicy: Always
  terminationGracePeriodSeconds: 30
  dnsPolicy: ClusterFirst
  serviceAccountName: default
  serviceAccount: default
```

Под после мутации по политикам опубликованным ранее:

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    run: nginx
  annotations:
    busybox-injection: enabled
    kblt.mutation.resource: 'true'
spec:
  containers:
    - name: nginx
      image: nginx
      resources: {}
      imagePullPolicy: Always
    - name: busybox
      image: busybox
      command:
        - /bin/sh
      args:
        - '-c'
        - >-
          while true; do echo 'Hi I am busybox sidecar. I was created at' $(date -u);
          sleep 5;done
      resources: {}
      imagePullPolicy: Always
  restartPolicy: Always
  terminationGracePeriodSeconds: 30
  dnsPolicy: ClusterFirst
  serviceAccountName: default
  serviceAccount: default
```

Затем удалим под nginx:

```shell
kubectl delete pod nginx -n kubelatte-sandbox
```

### Креация

Креация - это создание произвольного ресурса в кластере. Главное отличие от мутационных triggers является наличие поля creationConfigs. 

### Валидация
